Risc World 3/Risc World 3.iso/SOFTWARE/ISSUE4/ZAP/!Install

Text File | 2002-10-22 | 17KB | 330 lines

Chapter 2: Installation: making sure everything's in the right place
--------------------------------------------------------------------

       Zap is a fairly complex application, and while you _can_ just copy
       it onto your hard disc, it is better if you set it up properly. This
       will only take a couple of minutes, and has a number of benefits
       (although in general you won't notice them directly - you just won't
       get irritated by some of the things that can go wrong if you _don't_
       set it up properly).

       See section 2.4 if you are upgrading from Zap v1.40 or later.
       Unfortunately there is no simple upgrade path from earlier versions
       of Zap, because both the configuration and the layout of files
       within Zap itself have altered. We apologise for the inconvenience
       this causes.

   2.1 Getting the right files

       Zap comes in a number of parts. Which parts you need will depend on
       what you're intending to do.

       Firstly there is the core distribution, which contains merely
       those files _required_ to get Zap running. While this will give
       you a usable text editor, it will be missing many of the more
       sophisticated features described in this manual.

       Secondly there is a group of extensions which is _recommended_;
       you don't need these to run Zap, but they provide lots of useful
       features which you will probably want.

       Thirdly, there are some _optional_ extensions which many people
       won't need, but which some people will find useful.

       The core distribution is supplied in one archive, the name of which
       will depend on which version you decided to download. There are
       three core packages:

        -  zap.zip. This is the smallest archive, containing just the files
           needed to get Zap running.

        -  intl.zip. As above, but adds French and German translations.

        -  devel.zip. As above, but adds some tools which may be useful to
           authors of Zap extension modes.

       This is the first thing you should set up; this process is described
       below in section 2.2.

       There are a number of extension modes which you may also have
       downloaded - once you've set up Zap itself, you can install these;
       see section 2.3 below.

       The following additional archives are optional:

        -  zfonts.zip - a full ZapFonts distribution, containing lots and
           lots of fonts. Generally you don't need this for Zap, since the
           core archive comes with a minimal ZapFonts distribution; however
           ZapFonts is used by some other applications, so you may want the
           additional fonts for use with them. See section 2.2.2 below for more
           information.

   2.2 Core setup

       The Zap core distribution contains an Install file (this document
       in text format), the !Zap, !ZapFonts and !ZapUser application
       directories, and a couple of other utilities. Please don't just copy
       it onto your hard disc - this is extremely limiting.

       Let's look at where they should be going. We'll deal with ZapUser
       first.

 2.2.1 ZapUser: user configuration files

       ZapUser is designed to keep all your preferences and settings in
       one place. This means that you can copy it onto a floppy disc, take
       it to another computer, and have exactly the settings that you want
       there too.

       If you have a RISC PC-style boot structure (as most people do - see
       below if you don't), then you want to put ZapUser in Boot:Choices
       (Shift double-click on !Boot on your main hard disc, and then
       double-click on Choices in the directory viewer that come up; then
       you can move the !ZapUser application by Shift dragging).

       If you _don't_ have a RISC PC-style boot structure, then you
       have a choice. If you have a boot structure then you can try to
       find a place to put ZapUser in that, so that it will get booted
       _before_ Zap (wherever you put Zap). If you can't do that, or don't
       know what it means, then it's best to put ZapUser inside Zap, as
       !Zap.!ZapUser. While that's far from ideal, it's a lot easier than
       setting up a boot structure just to deal with ZapUser.

       You can use ZapUser to have multiple configurations on one machine.
       To change from one to another, just double-click on the ZapUser
       you want to use, and then quit and restart Zap. A range of sample
       configurations should be available from wherever you obtained Zap -
       see section 15.2.

 2.2.2 ZapFonts: the global bitmap font resource

       ZapFonts is the global bitmap font resource; it is to bitmap fonts
       what !Fonts is to outline fonts. Zap uses bitmap fonts in all its
       file windows, and several other applications also use it, including
       _Messenger_ and _FreeTerm_. Consequently we want it to be somewhere
       that they can all get at it.

       If you have a RISC PC-style boot structure, then you want to put
       ZapFonts in Boot:Resources. If you don't have a RISC PC-style boot
       structure, then you need to find another place to put ZapFonts so
       that it will boot before Zap. If you absolutely can't do this, then
       you should put ZapFonts inside the !Zap directory as !Zap.!ZapFonts,
       and make sure that Zap boots before anything else which might
       need ZapFonts. The best way to do this is to have Zap in the root
       directory of your main hard disc; however we strongly suggest that
       you use a boot structure of some sort - there are a number of free
       ones available which should suffice.

       Because ZapFonts supplies all the bitmap fonts for all the
       applications that want to use it, the complete distribution is
       fairly large. Consequently the version in the core Zap distribution
       is minimal, containing only a couple of fonts. The complete set is
       available from wherever you got Zap from (see section 15.2); it will
       come as a !ZapFonts application directory which you can simply copy
       it over the top of your installed !ZapFonts directory. You may need
       to restart some applications to get them to recognise the new fonts
       (this isn't true of Zap, which will recognise automatically that you
       have installed new fonts).

       For more information on using ZapFonts, please see the documentation
       supplied inside its application directory.

 2.2.3 Support files

       Zap comes with some additional support files, !Country, !!DeepKeys
       and DDEU_Patch which you'll want to deal with when you're setting it
       up.

       It also comes with an Obey file, DontRun, which is supplied to
       assist upgrading configuration from v1.40 to v1.45 - see section 2.4
       for more information.

2.2.3.1 !Country

       !Country is a small utility that you should run at startup which
       determines the country you've set your computer up for. Ideally
       you should place it in Boot:Choices.Boot.PreDesk on a recent boot
       system, so it will be run before anything else, and indeed it is
       supplied inside a !Boot structure that you can copy over your
       current one. !Country sets the environment variable `Sys$Country'
       to whatever your current country is. Zap uses this in its
       internationalisation support (see section 12.4).

2.2.3.2 !!DeepKeys

       !!DeepKeys is a utility that should be run at startup which tries to
       stop RISC OS from losing modifier keys (such as Shift, Ctrl etc.).
       As for !Country, it should live in Boot:Choices.Boot.PreDesk, and is
       also supplied inside a !Boot structure to make this easier.

2.2.3.3 DDEU_Patch

       DDEU_Patch patches DDEUtils so that Zap can read the current prefix
       directory for a taskwindow. You should only run it if you're using
       version 1.53, 1.54 or 1.55 of DDEUtils. Versions later than 1.55
       do not need to be patched since they already include the necessary
       code.

       To check which version you have:

         *Help DDEUtils

       If this reports "No help found", then

         *Load System:Modules.DDEUtils
         *Help DDEUtils

       Version 1.54 is supplied in the standard !Boot, and version 1.59 is
       the first version to be included in ROM.

   2.3 Extensions setup

       Any extension archive you downloaded will contain a directory !Zap
       which should be copied over !Zap.

       Alternatively, you can install just some of the extensions. If you
       are fairly confident, you can do this yourself by simply copying
       the relevant applications _from_ the !Zap.Modules directory of the
       archive _into_ !Zap.Modules in your installed setup.

       You will then need to quit and restart Zap to complete the setup.

   2.4 Upgrading from Zap v1.40 or later

       To upgrade from Zap v1.40 or later, you need to do three things.

        -  Replace !Zap - see section 2.4.1

        -  Upgrade !ZapFonts - see section 2.4.2

        -  Upgrade !ZapUser - see section 2.4.3

 2.4.1 Replacing !Zap

       Since all configuration is now held in !ZapUser, there is almost
       nothing which most people need to alter inside !Zap itself these
       days - including the extensions. This means that you should simply
       be able to replace your current !Zap application directory with a
       new one constructed from the core archive and whatever extensions
       you need, as explained earlier. Please _don't_ copy the new !Zap
       application over your old one since that will cause problems as some
       files have been relaced by directories - delete your existing !Zap
       first.

       Note that this won't work smoothly if you have been keeping
       !ZapFonts or !ZapUser inside the !Zap application directory. If
       you are doing so, please consider trying to find an alternative
       solution, because it will make your life much easier.

 2.4.2 Upgrading !ZapFonts

       The only change in !ZapFonts since Zap v1.40 was released is a new
       version of the ZapRedraw module. You should copy the new one from
       inside !ZapFonts in the core archive into your working !ZapFonts
       application directory. Alternatively, simply copy the new !ZapFonts
       over your old one.

 2.4.3 Upgrading !ZapUser

       The changes to upgrade your configuration from Zap v1.40 to Zap
       v1.45 are involved, however two facilities are available to assist
       the process:

        -  If you have Perl, you can download a script that will do
           the majority of the work for you - this is available from
           http://zap.tartarus.org/ftp/pub/1.45/upgrade-config.pl.

        -  The Zap developers are providing an upgrade service - package
           your !ZapUser into a Zipfile and send it via email to
           [e-mail]. One of the developers will upgrade your
           configuration for you and return it to you.

       If you want to upgrade your configuraton yourself, the following
       changes need to be made. All the files referred to below are in
       !ZapUser.Config.

       If you are upgrading from Zap v1.42 or later, some of these changes
       may be unnecessary for you.

        -  !ZapBoot has changed substantially; it is suggested that you copy
           the new version over and make any changes you need. In practice, you
           are unlikely to have changed anything, except perhaps the file type
           claims (lines such as ZapRunType FFF).

        -  !ZapRun has changed substantially to support internationalisation;
           it is suggested that you copy the new version over and make any
           changes you need. In practice, the only parts you are likely to have
           changed are the templates set, and perhaps the file type claims.
           Note that some template sets haven't been updated for v1.45, and
           so aren't supplied any more. In addition, note that the old system
           variables `Zap$HelpPath_<mode>' are no longer required.

        -  Country has been added to support internationalisation; it can be
           used to override your system country. You should copy this file
           over, but only edit it if you need to set your country explicitly.

        -  Settings has had two variables added. &322 can be used to specify a
           command to execute on startup, and &323 specifies the default mode.
           See section 12.3.1 for more information.

        -  A directory TMFs has been added. You should copy this across. TMFs
           (Textual Mode Files) are files that set per-mode variables, used to
           make some commands and operations more configurable. (See section
           12.3.6 for more information.) If you are upgrading from v1.42 or
           later, you will already have this directory present; however it may
           contain TMFs which are now unnecessary. Unless you have edited any
           of these yourself, you should only have TMFs for core modes (Text,
           Byte, HalfWord, Word, DoubleWord, ASCII and Code) in this directory.

        -  Two new files, FileIdHigh and FileIdLow, have been added. These
           should be copied across. They allow modes to be selected on loading
           files based on the contents of the start of the file.

        -  The Keys file has changed significantly; firstly, the method of
           specifying alternate keymaps has changed from using &400 variables
           in a block, to using &800 variables immediately before the keymap in
           question, to declare them. Secondly, support for country-specific
           Keys files has been added; instead of a single file, you should
           have a directory, ZapUser:Config.Keys, containing a file for each
           country (eg: ZapUser:Config.Keys.UK, ZapUser:Config.Keys.France).
           Unless you made significant alterations to your keys file, we
           suggest that you copy in the new Keys directory and make any changes
           you need. Alternatively, move your current ZapUser:Config.Keys to
           ZapUser:Config.Keys.UK (or another country name, as appropriate),
           and edit it to use the new file format. See section 12.4 for more
           information about internationalisation, and section 12.3.3 for more
           information about the new Keys file format.

        -  Also, some extension modules have their own Keys files. They may
           also be configured to use their keymaps by default; you can override
           this by altering the relevant module's TMF file (see section 12.3.6
           for more information).

        -  The Menus file has also become internationalised, in the same
           way. In addition, we now generate menus files from a source
           format which allows you to name menus instead of referring to
           them by number. Further, areas of the source file can be made
           optional - the idea is that more or less everyone can use the
           same source file, while still being able to configure things a
           fair amount. We strongly suggest that, if you don't like the new
           default menus, you copy the new menus directory, look at, and
           possibly edit, the appropriate source file (they are supplied in
           the directory ZapUser:Config.Menus.Source), and generate your
           menus file from that. See section 12.4 for more information about
           internationalisation, and section 12.3.5 for more information about
           the new Menus source format, and the method for generating the final
           file from source.

       --------------------------------------------------------------------

       Now you have a working version of Zap. If you currently have an
       older version of Zap running, you should quit it; now you should
       double-click on both ZapUser and ZapFonts to make sure that they are
       setup correctly in their new locations. Finally you can double-click
       on Zap to load it.

       The next section in the manual is chapter 3, which introduces you
       to the basic editing facilities of Zap. Even if you have used Zap
       before we advise that you at least skim through this section, to
       make sure you haven't missed any of the useful functions available.